Tapir 1.0, release 09/06/07 19:50
======================================

Features
--------
Internals:
 * The version of the saved TZX file is the lowest possible considering the content
 * RealMic engine - Speccy Mic circuitry is emulated so that the WAV file produced contains the signal as outputted from the Speccy Mic plug (before being altered by any tape deck circuitry)

Mouse:
 * Doubleclick either collapses/expands group of loop, or serves as a shortcut for View data
 * Right click selects blocks, holding shift or right-dragging selects contiguous blocks
 * Ctrl+right click - context menu
 * Drag&drop can be used for moving blocks or copying (when holding ctrl).
   Dragging/deleting non-selected block moves/copies/deletes only this one block, dragging/deleting selected block moves/copies/deletes the whole selection.
   For purpose of drag&drop/delete, collapsed groups/loops acts as one big block.
 * It is possible to drag&drop TZX files onto the tape windows to load them.
   When holding shift, Tapir inserts the file at cursor.
 * Accelerated autoscrolling when dragging out of window

Status bar:
 * Dec/Hex - selects the number base for ALL the numbers (also e.g. in BASIC listing, including the FP numbers!), the ONLY exception is the Sample rate dialog box
 * Block compare: selects the method for comparing blocks
     data only - for block containing some data, it compares only the data
     data+timings - compare also the timing constants, but ignore the pause
     data+timings+pauses - compare everything, including the pause
 * Tape compare: selects the method for comparing the whole tapes.
   Each comparing of two blocks is affected by the Block compare setting.
     datablocks only - compare only the datablocks, ignore other blocks
     ignore metadata - compare all blocks that has something to do with the tape signal modification (like rows of pulses, but also clearly the datablocks)
     all blocks - do not ignore any block during the compare
 * Lock/Unlock - for safety reasons you cannot modify anything when locked

Menu:
 * Block->Find match - finds matches for the current block on both tapes (using the Block compare method). Matches are shown in green.
 * Compare tapes - compares the two tapes. Blocks shown in light gray were ignored during compare, block shown in magenta differ, block shown in their respective colours are the same.
 * Check consistency - checks for corrupted blocks, useless blocks (like loops 0 or 1 times), infinite loops, forbidden nesting, calls without returns etc.
 * View selected as one - you can view the content of the selected blocks as they were one contiguous datablock
                          (useful e.g. for viewing the screen if divided into more smaller blocks - Speedlock, Dinaload, Bleepload...)
                          Collapsed groups act as one block (i.e. if you have a screen divided into many subblocks enclosed in a Group statement, then just collapse the group, right-click this collapsed group and choose View selected as one).
 * Set selection timings to current - all timings (except of the pause value) of datablocks in the selection of the respective window are set to the timings currently displayed (this allows to 'copy' the timings from one datablock to another)

Generalized data editing:
  Symbol tables - each line represents one symbol and has a format [symbol code]:symbol flags;pulse1,pulse2,..,pulseN
                  Different symbols can consist of different number of pulses.
                  Symbol code is only optional and Tapir automatically substitutes the proper symbol code based on the position of the symbol in the list (in fact, everything before the colon is ignored).
  Pilot/sync stream - the format is code1, rep1; code2, rep2; .... codeN,repN
                      where codeI refers to the symbol code from the symbol table and repI is the number of repetitions of codeI.
  In both of these tables, the differentiation between ';' and ',' is purely cosmetic and you may use whichever separator of the two that you want.
  All spaces are ignored.

Custom info POKEs editing:
  The field POKEs has the following syntax:
  Each POKE is on its own line, and the statement is
  [POKE] [page:]adr,val[/orgval],
  where the information in square brackets is optional.
  The val field can contain also the question mark sign ('?'), which means, that an emulator should ask for this value.

Custom info Decode info:
  See documentation on Decode info.
  HINT - If any of the scripts has bugs (like endless loops), you can interrupt the script by pressing ESC.
         If the script is running over more blocks (like computing checksum for all the blocks), you may need to press ESC as many times as there are blocks.

Data Window:
  All controls in the upper portion are relevant only to the appearance/interpretation of the data. All controls in the lower portion directly affect the data contents.
  View controls:
   Raw length - the length of the datastream before the interpretation/decryption takes place.
   Length - the length of the interpreted/decrypted data.
   Flip bytes - if checked, it is assumed that the bytes are constructed by an RR instruction (rather than RL, as usual).
                An example of this is Rick Dangerous 2.
   Reverse order - if checked, it is assumed that the data is loaded backwards, starting at the Base address.
                   An example of this is Star Wars (Haxpoc-Lock scheme) - set base address to $5aff and activate reverse order and the screen will be shown correctly.
   Decrypt data - if a decryption script is supplied, this decrypts the data
   Hide flag byte - the first bytes (determined by the Decode info) of the datablock is considered to be a flag byte, hence excluded from the interpretation of the data
   Hide checksum byte - the bytes of the datablock specified in the Decode info are considered to be a checksum, hence excluded from the interpretation of the data
   Base address - the address at the Speccy memory where the block is put at. All interpretation of the data depends on the base address.
                  Screen - the screen starts at 16384, so if the base address is set to 16384, the first 6912 of the datablock is shown.
                           If the base address is set to 0, the screen shows 6912 bytes starting at the offset 16384 in the datablock.
                  System variables - start at 23552
                  BASIC listing - program starts at PROG, variables at VARS
                                  One more example - if Base address is set to 10 and PROG is set to 13, then the BASIC listing starts to interpret the data from the 4th byte of the datablock
   Dump - you can edit the content of the raw data stream, i.e. provided that all the decode modifiers (decrypt, flip bytes, reverse order, hide flag, hide checksum) are off
        - Search pattern: you can enter dec/hex values in the left box or/and the ascii characters in the right box, backspace deletes the last value entered.
                          You can also enter '?' (question mark) in the left box instead of a value - this matches any byte.
                          (Say you want to find any call to address around the ROM LD-BYTES. For this, your search pattern would be CD ??? 05.)
   BASIC listing - Show numbers - shows the 'real' values of the numbers
                   Speccy formatting - 32 characters per line and a limited interpretation of BASIC control codes
                   128k BASIC - interpret <graph t> and <graph u> as 128k BASIC commands

  Edit controls:
   These act directly on the data stream, i.e. on the data BEFORE the interpretation/decryption takes place.
   The buttons in the upper row operate on bits, the buttons in the lower row operate on bytes.
   The number of bits/bytes for the operation is entered into the edit box to the right of the buttons; let us denote this value by N.
   Drop - drops the last N bits/bytes in the data stream.
   Add - adds N bits/bytes to the data stream.
   Shift left - removes the first N bits/bytes in the data stream
   Shift right - adds N bits/bytes before the data stream
   Last byte mask - graphical representation of the valid bits in the last byte. You can specify the number of trailing bits by directly clicking on this control.

Known bugs:
-----------

Todo: (listed in the order of importance/complexity ratio)
-----

 internals:
 ..........

  better dump/disassembly synchronisation

 GUI:
 ....

  Better icon
  Help

 Requests:
 .........

* (Andy) On the Data Window [Screen], the ability to save to GIF or AnimGIF for Flash Attribute
* (Andy) Determine loader, display in box somewhere.
* (Andy) Infoseek lookup to populate Archive Info blocks. Dunny should know all about this ;-) Still it could be useful.
* (Andy) Compare existing TZX to new algorithm, suggest update where appropriate (red, blue or some colour to indicate)

Notes:
------
Control character [cursor back] implementation in BASIC listing is only approximate.


Changes:
--------
since release 09/06/07 19:50
 * fixed a discrepancy and a bug in the routine that decides the minimum TZX version based on the file content

since release 06/12/19 01:30
 * changed behaviour of View as Screen: if data reversed, the baseaddress is set to $5aff
 * a check for '0 dimension' added into Variables listing, so that garbage input doesn't end in "Out of memory".

since release 06/12/21 01:00
 * corrected 'Left tape info' caption for right tape
 * fixed a typo in the BASIC Speccy formatting

since release 06/12/22 14:30
 * fixed a bug in the joining of non byte-aligned blocks
 * fixed a typo that caused exceptions when group checksumming non-closed groups
 * fixed non-updating current TZX file version after save
 + added selection timings setting

since release 06/12/30 21:00
 * updated the hardware list in the hardware info block, as proposed by Mike Wynne

since release 07/01/09 14:00
 + added a check to avoid loading corrupted files

since release 07/01/09 19:30
 * fixed bugs in the interpreter's assembler: 'labels as immediate values' and 'register as jump operands' should now be correctly assembled
 * fix in the interpreter - the opcodes for cmp/mul were switched (a typo)
 * fixed some bugs when working with Generalized data block that has empty data
 * fixed header type when editing the header
 * numbers in BASIC - removed the test for the fifth byte of an integer number being zero (the real BASIC interpreter ignores this fifth byte) - now you can examine the DI protection more easily :o)
 * better error message for Generalized data block if no symbols defined for non-empty datablock
 * fixed mnemonics in Z80 assembler - 'ex sp,(hl)' changed to 'ex (sp),hl
 + added a check for zero number of dimensions in Variable listing, so that garbage input doesn't cause an exception
 + 'Hide attributes' option added in View as screen mode
